Each GLS command is classified as either global, immediate, or encodable.
All immediate and encodable commands use the GLS context state.
The commands ggggllllssssGGGGeeeennnnCCCCoooonnnntttteeeexxxxtttt(((()))), ggggllllssssDDDDeeeelllleeeetttteeeeCCCCoooonnnntttteeeexxxxtttt(((()))), and ggggllllssssCCCCoooonnnntttteeeexxxxtttt(((()))) (see
below) are global. All other GLS commands described on this page are
non-global. Each client thread has a state variable that always contains
either zero (the initial value) or the name of the thread's current GLS
context.
* If the value is zero, all non-global GLS commands are no-ops, and
non-global GLS commands that return a value return zero.
* If the value is nonzero, all non-global GLS commands use the state
in the issuing thread's current GLS context.
At any given instant, a GLS context may be current to at most one thread.
The following functions are available for working with contexts:
For basic stream capture, call ggggllllssssBBBBeeeeggggiiiinnnnCCCCaaaappppttttuuuurrrreeee(((()))).
Between a ggggllllssssBBBBeeeeggggiiiinnnnCCCCaaaappppttttuuuurrrreeee(((()))) command and the following ggggllllssssEEEEnnnnddddCCCCaaaappppttttuuuurrrreeee(((())))
command, the current GLS context is in _c_a_p_t_u_r_e _m_o_d_e. In capture mode,
all commands are captured instead of executed:
* All GL commands are captured by GLS instead of being sent directly
to GL and executed.
* All encodable GLS commands are captured instead of being sent
directly to GLS and executed.
The command ggggllllssssBBBBeeeeggggiiiinnnnCCCCaaaappppttttuuuurrrreeee(((()))) opens a stream for writing and then encodes
the command ggggllllssssBBBBeeeeggggiiiinnnnGGGGLLLLSSSS(((()))). The command ggggllllssssEEEEnnnnddddCCCCaaaappppttttuuuurrrreeee(((()))) encodes the
command ggggllllssssEEEEnnnnddddGGGGLLLLSSSS(((()))) and then closes the currently open GLS stream.
ggggllllssssBBBBeeeeggggiiiinnnnCCCCaaaappppttttuuuurrrreeee(((()))) and ggggllllssssEEEEnnnnddddCCCCaaaappppttttuuuurrrreeee(((()))) have the following prototypes:
Here's how the different values for _i_n_S_t_r_e_a_m_T_y_p_e affect the capture
process:
* If _i_n_S_t_r_e_a_m_T_y_p_e is GGGGLLLLSSSS____CCCCOOOONNNNTTTTEEEEXXXXTTTT, ggggllllssssBBBBeeeeggggiiiinnnnCCCCaaaappppttttuuuurrrreeee(((()))) opens an in-memory
stream named _i_n_S_t_r_e_a_m_N_a_m_e that is stored in the current GLS context.
Within the constraints of available memory, a GLS context can
contain an arbitrary number of named GGGGLLLLSSSS____CCCCOOOONNNNTTTTEEEEXXXXTTTT streams.
GGGGLLLLSSSS____CCCCOOOONNNNTTTTEEEEXXXXTTTT streams can be thought of as client-side display lists
that complement the server-side display lists provided by core GL.
* If _i_n_S_t_r_e_a_m_T_y_p_e is GGGGLLLLSSSS____BBBBIIIINNNNAAAARRRRYYYY____LLLLSSSSBBBB____FFFFIIIIRRRRSSSSTTTT, GGGGLLLLSSSS____BBBBIIIINNNNAAAARRRRYYYY____MMMMSSSSBBBB____FFFFIIIIRRRRSSSSTTTT, or
GGGGLLLLSSSS____TTTTEEEEXXXXTTTT, the name of the opened stream is formed by appending
_i_n_S_t_r_e_a_m_N_a_m_e to a write-prefix string that is stored in the current
GLS context.
Use ggggllllssssWWWWrrrriiiitttteeeePPPPrrrreeeeffffiiiixxxx(((()))) to replace the value of the write-prefix
string. See "Modifying Stream Capture and Playback" below.
* If _i_n_S_t_r_e_a_m_T_y_p_e is GGGGLLLLSSSS____BBBBIIIINNNNAAAARRRRYYYY____LLLLSSSSBBBB____FFFFIIIIRRRRSSSSTTTT, GGGGLLLLSSSS____BBBBIIIINNNNAAAARRRRYYYY____MMMMSSSSBBBB____FFFFIIIIRRRRSSSSTTTT, or
GGGGLLLLSSSS____TTTTEEEEXXXXTTTT, and _i_n_S_t_r_e_a_m_N_a_m_e is not the empty string (""), the command
ggggllllssssBBBBeeeeggggiiiinnnnCCCCaaaappppttttuuuurrrreeee(((()))) uses the standard C library command ffffooooppppeeeennnn(((()))) to
create a write channel of type FILE*.
* If _i_n_S_t_r_e_a_m_T_y_p_e is GGGGLLLLSSSS____BBBBIIIINNNNAAAARRRRYYYY____LLLLSSSSBBBB____FFFFIIIIRRRRSSSSTTTT, GGGGLLLLSSSS____BBBBIIIINNNNAAAARRRRYYYY____MMMMSSSSBBBB____FFFFIIIIRRRRSSSSTTTT, or
GGGGLLLLSSSS____TTTTEEEEXXXXTTTT, and _i_n_S_t_r_e_a_m_N_a_m_e is the empty string, and the GLS client
has used the command ggggllllssssWWWWrrrriiiitttteeeeFFFFuuuunnnncccc(((()))) specify a write callback
function, that function is used in place of the standard C library
function ffffwwwwrrrriiiitttteeee(((()))) to write bytes to the stream.
* If _i_n_S_t_r_e_a_m_T_y_p_e is GGGGLLLLSSSS____BBBBIIIINNNNAAAARRRRYYYY____LLLLSSSSBBBB____FFFFIIIIRRRRSSSSTTTT, GGGGLLLLSSSS____BBBBIIIINNNNAAAARRRRYYYY____MMMMSSSSBBBB____FFFFIIIIRRRRSSSSTTTT, or
GGGGLLLLSSSS____TTTTEEEEXXXXTTTT, and _i_n_S_t_r_e_a_m_N_a_m_e is the empty string, and if
ggggllllssssWWWWrrrriiiitttteeeeFFFFuuuunnnncccc(((()))) is not defined, ggggllllssssBBBBeeeeggggiiiinnnnCCCCaaaappppttttuuuurrrreeee(((()))) uses a default
write channel of type FILE* that is stored in the current GLS
context (initial value: stdout).
In that case, use ggggllllssssCCCChhhhaaaannnnnnnneeeellll(((()))) to replace the value of the default
write channel. See "Modifying Stream Capture and Playback" below.
What happens when you call ggggllllssssCCCCaaaallllllllSSSSttttrrrreeeeaaaammmm(((()))) depends on the value of
_i_n_S_t_r_e_a_m_N_a_m_e and other factors:
* If _i_n_S_t_r_e_a_m_N_a_m_e is the name of a GGGGLLLLSSSS____CCCCOOOONNNNTTTTEEEEXXXXTTTT in-memory stream stored
in the current GLS context, ggggllllssssCCCCaaaallllllllSSSSttttrrrreeeeaaaammmm(((()))) decodes that stream.
Otherwise, the command searches for an external stream to decode.
* If _i_n_S_t_r_e_a_m_N_a_m_e is not the empty string (""), a sequence of
potential external stream names is formed. The first names in the
sequence are formed by appending _i_n_S_t_r_e_a_m_N_a_m_e to each of the strings
in a list of read-prefix strings that is stored in the current GLS
context. The last name in the sequence is formed by appending
_i_n_S_t_r_e_a_m_N_a_m_e to the write-prefix string.
Use the commands ggggllllssssAAAAppppppppeeeennnnddddRRRReeeeaaaaddddPPPPrrrreeeeffffiiiixxxx(((()))) and ggggllllssssPPPPrrrreeeeppppeeeennnnddddRRRReeeeaaaaddddPPPPrrrreeeeffffiiiixxxx(((()))) to
modify the contents of the read-prefix string list. See "Modifying
Stream Capture and Playback" for more information.
Beginning with the first potential external stream name,
ggggllllssssCCCCaaaallllllllSSSSttttrrrreeeeaaaammmm(((()))) tries each successive name until either a readable
stream is found or all of the names have been tried. For each name,
the command ffffooooppppeeeennnn(((()))) is issued with the name as an argument, in an
attempt to create a read channel of type FILE*.
* If _i_n_S_t_r_e_a_m_N_a_m_e is the empty string, the command ggggllllssssCCCCaaaallllllllSSSSttttrrrreeeeaaaammmm(((())))
uses a default read channel of type FILE* that is stored in the
current GLS context (initial value: stdin). Use command ggggllllssssCCCChhhhaaaannnnnnnneeeellll(((())))
(see "Modifying Capture and Playback") to replace the value of the
default read channel.
* If _i_n_S_t_r_e_a_m_N_a_m_e is the empty string, and the GLS client has used the
command ggggllllssssRRRReeeeaaaaddddFFFFuuuunnnncccc(((()))) to specify a read callback function, that
function is used in place of the standard C library function ffffrrrreeeeaaaadddd(((())))
when bytes are to be read from the stream.
The command ggggllllssssCCCCaaaallllllllSSSSttttrrrreeeeaaaammmm(((()))) is encodable. When a GLS decoder reads this
command from a GLS stream, the decoder recursively decodes the GLS stream
named in the command. As a result, GLS streams provide the same
embedding capability on the client side that GL display lists provide on
* Call ggggllllssssCCCCaaaappppttttuuuurrrreeeeFFFFllllaaaaggggssss(((()))) to specify the destination of a command.
* Call ggggllllssssCCCCoooommmmmmmmaaaannnnddddFFFFuuuunnnncccc(((()))) to register a callback function.
* Call ggggllllssssAAAAppppppppeeeennnnddddRRRReeeeaaaaddddPPPPrrrreeeeffffiiiixxxx(((()))) or ggggllllssssPPPPrrrreeeeppppeeeennnnddddRRRReeeeaaaaddddPPPPrrrreeeeffffiiiixxxx(((()))) to modify the
read prefix string list.
* Call ggggllllssssWWWWrrrriiiitttteeeePPPPrrrreeeeffffiiiixxxx(((()))) to replace the value of the write prefix
string.
* Call ggggllllssssCCCChhhhaaaannnnnnnneeeellll(((()))) to replace the value of the default write channel
ggggllllssssCCCCaaaappppttttuuuurrrreeeeFFFFllllaaaaggggssss(((()))) allows a GLS client to specify on a per-opcode basis
whether a captured GL or encodable GLS command is written to the open
ggggllllssssCCCCoooommmmmmmmaaaannnnddddFFFFuuuunnnncccc(((()))) registers the client callback function _i_n_F_u_n_c for the GL
or encodable GLS command designated by _i_n_O_p_c_o_d_e. There are two types of
callback function: GGGGLLLLSSSS____CCCCAAAALLLLLLLL____FFFFUUUUNNNNCCCC and GGGGLLLLSSSS____CCCCAAAAPPPPTTTTUUUURRRREEEE____FFFFUUUUNNNNCCCC. The parameter
_i_n_A_t_t_r_i_b identifies the type of function to be registered.
When a GLS decoder reads a command from a GLS stream, and a GGGGLLLLSSSS____CCCCAAAALLLLLLLL____FFFFUUUUNNNNCCCC
function has been registered for that command, the decoder calls that
function instead of issuing the command.
When GLS captures a command, and a GGGGLLLLSSSS____CCCCAAAAPPPPTTTTUUUURRRREEEE____FFFFUUUUNNNNCCCC function has been
registered for that command, GLS calls that function instead of the
standard GLS capture function for that command. If desired, the callback
function may call the standard GLS capture function, which is named
ggggllllssssAAAAppppppppeeeennnnddddRRRReeeeaaaaddddPPPPrrrreeeeffffiiiixxxx(((()))) and ggggllllssssPPPPrrrreeeeppppeeeennnnddddRRRReeeeaaaaddddPPPPrrrreeeeffffiiiixxxx(((()))) can be used to change
the name given to ggggllllssssCCCCaaaallllllllSSSSttttrrrreeeeaaaammmm(((()))). They have the following prototypes:
